🕸️ Ada Research Browser

PLAN.md
Home›Research Reports›PLAN.md
← Back

OpenClaw Mission Control — Implementation Plan

Version 1.0 · Authored by Ada · March 2026
Target: Hand-off ready for Claude Code implementation

0. Pre-Implementation Checklist

Install and configure these before writing a single line of feature code. Each one pays dividends throughout development.

Claude Code Skills / Hooks

Tool What it contributes
spec-driven-dev skill (clawhub) Generates feature specs and acceptance criteria from plain-language descriptions. Keeps implementation honest against the plan. Install before Phase 1 begins.
claude-code-review hook Runs automated code review on every commit or PR. Catches anti-patterns, security issues, and deviations from agreed architecture before they compound.
frontend-design skill (installed) Produces distinctive, production-grade UI components. Prevents generic AI aesthetic. Use from Day 1 of UI work.
gh-issues skill (installed) Automates GitHub issue→implementation→PR loop. Critical for Phase 1+ when multiple features run in parallel.
openai-whisper-api skill (installed) Provides voice input baseline for the voice command feature without building from scratch.

MCP Servers

MCP Server What it contributes
@modelcontextprotocol/server-filesystem Lets Claude Code read/write project files directly during implementation. Required for any file-browser features.
@modelcontextprotocol/server-github Direct GitHub API access for PR tracking, issue sync, and CI status in the mission control UI.
@modelcontextprotocol/server-sqlite (or postgres) Schema inspection and query generation during database work. Speeds up migration writing significantly.
mcp-server-playwright Browser automation for E2E test generation. Generates test stubs from UI flows automatically.

Dev Infrastructure

Tool What it contributes
Vitest + Playwright Unit + E2E test harness. Set up before any feature ships. A mission control without tests is itself unmonitorable.
Storybook Component isolation for the design system. Prevents UI regressions across the 20+ screens.
OpenAPI/Swagger codegen Generate typed API clients from the backend spec. Eliminates hand-written fetch boilerplate across frontend.
Biome or ESLint + Prettier Code quality gates. Set up in CI before any PR can merge.

1. Vision & Design Principles

What This Is

OpenClaw Mission Control is a self-hosted, real-time command center for Sean's AI agent infrastructure. It provides a unified interface to monitor, direct, and debug every agent session running on the OpenClaw gateway — including Claude Code, Codex, Gemini CLI, and OpenClaw's own sub-agent system. It is the difference between flying blind and flying with instruments: you can see what every agent is doing, why it costs what it costs, and intervene in under 10 seconds from any device including a phone.

Core Design Principles

  1. Gateway-native, not bolted-on. Every feature is built around the OpenClaw gateway WebSocket and REST API. We do not poll filesystem hacks or process-inspect workarounds. Real data, real-time, real control.

  2. Phone-first monitoring, desktop-first control. You will check status from your phone 10x more often than you'll spawn agents. Mobile must be first-class for reads. Desktop gets the power controls. Both are the same app.

  3. Zero-downtime agent operations. Viewing, filtering, and navigating the dashboard must never interrupt running agents. Read paths are fully decoupled from write paths.

  4. Opinionated defaults, configurable everything. The system ships with sensible alert thresholds, panel layouts, and notification routing out of the box. Every default is overridable. Power users aren't blocked; beginners aren't overwhelmed.

  5. Cost visibility is non-negotiable. Every agent session, every model call, every cron run shows its token cost. Surprises on the credit card bill are a failure mode.

  6. Self-monitoring. The mission control system itself is observable. If it goes down, you know before your agents do. Health checks, uptime metrics, and self-alerts are part of the core spec.

  7. Homelab-native deployment. Runs on Sean's Proxmox infrastructure behind Traefik reverse proxy with Tailscale access. No cloud dependency, no SaaS lock-in, no mandatory public exposure.

What It Is NOT

2. Feature Hierarchy

Tier 1 — Core (MVP, must ship)

# Feature Description
1 Live Agent Dashboard Real-time list of all active/idle/error agent sessions with status, model, cost, and uptime.
2 Session Inspector Drill into any session to see full message history, tool calls, token counts, and timeline.
3 Agent Spawn Launch a new agent session with configurable model, prompt, persona, and channel target.
4 Session Control Send messages to, pause, resume, or terminate any running agent session.
5 Cron Job Viewer List all scheduled jobs with next-run time, last-run result, and success/failure history.
6 Cost Dashboard Per-session and aggregate token usage, model cost breakdown, daily/weekly totals.
7 Real-time Event Stream Live feed of all gateway events (session started, message sent, tool called, error, etc.).
8 Alert System Push/Telegram/Discord notifications for critical events (agent down, cost spike, cron failure).
9 Auth + Access Control Secure login with at minimum password auth; only authorized users can control agents.
10 Mobile-Responsive UI All Tier 1 views are usable on a phone (350px+ width). Read paths are thumb-friendly.

Tier 2 — Enhanced (v1.1–v1.5)

# Feature Description
11 Cron Job Editor Create, edit, enable/disable, and manually trigger cron jobs from the UI.
12 Agent Task Kanban Visual board (Inbox → In Progress → Review → Done) for tasks assigned to agents.
13 Multi-Agent Pipeline Builder Define sequential or parallel agent pipelines; monitor aggregate progress.
14 GitHub Integration Link sessions to PRs and issues; show CI status; surface agent-authored commits.
15 Model Config Panel View and update active model, temperature, context window, and tool permissions per agent.
16 Skills & Plugins Viewer Browse installed skills, see which agents have access, enable/disable per-agent.
17 Notification Routing Config UI-based alert rules: what triggers what alert, delivered where, with what severity.
18 Session Search & Full-Text History Search across all historical session transcripts by keyword, date, agent, or model.
19 Cost Budgets & Thresholds Set daily/monthly spend caps per agent or globally; auto-alert when approaching.
20 Dark/Light Mode + Theme Full theme system with dark mode default, plus at least one light variant.

Tier 3 — Advanced (v2+)

# Feature Description
21 Voice Command Input Whisper-based voice-to-text for issuing commands to agents hands-free.
22 3D Agent Graph Visual node graph of active agents, sessions, and pipelines (inspired by tenacitOS).
23 Predictive Cost Modeling ML-based burn rate forecasting (inspired by Claude-Code-Usage-Monitor P90 model).
24 Agent Replay Step through any historical session replay with annotations and tool call inspection.
25 Wake-Word Activation Always-on voice trigger for mobile/desktop alert acknowledgment (inspired by ClawControl).
26 Exported Reports PDF/CSV session cost and performance reports for given date ranges.
27 Plugin Marketplace Integration Browse and install ClawHub skills from within the dashboard.
28 Multiplayer Collaboration Multiple users can co-view sessions with cursor presence (inspired by agor).

Out of Scope

3. User Roles & Permissions

Role Description Permissions
Owner Sean. Full control over everything. All reads + all writes + config + delete + user management
Admin Trusted collaborator with operational access. All reads + spawn/control agents + manage cron + manage alerts. Cannot delete agents or change auth settings.
Viewer Read-only observer (e.g. auditing, demos). All reads + no writes. Cannot see raw API keys or sensitive config values.
Agent (system actor) The OpenClaw gateway itself, or sub-agents posting status events. Write to event bus only. Cannot read other sessions or modify system config.
Guest Time-limited, scoped view-only access. Token-authenticated, expires in 24h. Specific sessions or specific dashboard panels only. No global views.

Permission Matrix (key operations):

Operation Owner Admin Viewer Agent Guest
View all sessions ✅ ✅ ✅ ❌ scoped
Spawn agent ✅ ✅ ❌ ❌ ❌
Send message to agent ✅ ✅ ❌ ❌ ❌
Terminate session ✅ ✅ ❌ ❌ ❌
Manage cron jobs ✅ ✅ ❌ ❌ ❌
View costs ✅ ✅ ✅ ❌ ❌
Edit model config ✅ ❌ ❌ ❌ ❌
Manage users ✅ ❌ ❌ ❌ ❌
Post events ❌ ❌ ❌ ✅ ❌

4. Core User Flows

Flow A: Agent Monitoring

flowchart TD
    A([Open Dashboard]) --> B[Agent List Panel\nall sessions, live status]
    B --> C{Agent status?}
    C -->|Healthy| D[View metrics\ntoken rate, cost, uptime]
    C -->|Warning| E[Click agent row\nopen Session Inspector]
    C -->|Error/Down| F[Alert badge highlighted\nclick to inspect]
    E --> G[Session Inspector\nmessage history + tool calls]
    F --> G
    G --> H{Action needed?}
    H -->|No| I[Return to dashboard]
    H -->|Yes| J[Send message / Terminate\nvia Session Control]
    J --> K[Action confirmed\nsession updated in real-time]
    K --> I

Flow B: Spawn & Direct Agent

flowchart TD
    A([Click Spawn Agent]) --> B[Spawn Dialog\nmodel, persona, prompt, channel]
    B --> C[Optionally: attach task\nfrom kanban or GitHub issue]
    C --> D[Submit → gateway POST /sessions]
    D --> E{Session created?}
    E -->|Success| F[Session appears in Agent List\nstatus: Initializing]
    E -->|Error| G[Error toast\nshow gateway error message]
    F --> H[Status → Active\nstream begins in Inspector]
    H --> I[Monitor output in real-time]
    I --> J{Intervention needed?}
    J -->|Send message| K[Type in command input\nPOST /sessions/:id/message]
    J -->|All good| L[Wait for completion]
    K --> I
    L --> M[Session status → Done\ncost summary shown]
    M --> N[Review output\nmark task complete if kanban-linked]

Flow C: Cron Job Management

flowchart TD
    A([Open Cron Panel]) --> B[Cron Job List\nschedule, last run, next run, status]
    B --> C{User action?}
    C -->|View details| D[Job Detail\nrun history, last output, error log]
    C -->|Create new| E[Cron Editor\nexpression, agent target, prompt template]
    C -->|Edit existing| F[Edit existing job\nsame editor]
    E --> G[Validate cron expression\nlive preview of next 5 runs]
    F --> G
    G --> H[Save → gateway PATCH /cron/:id]
    D --> I{Last run status?}
    I -->|Success| J[No action needed]
    I -->|Failed| K[View error details\nretry button]
    K --> L[Manual trigger\nPOST /cron/:id/trigger]
    L --> M[New run entry appears\nlive status update]
    H --> B

Flow D: Mobile Quick-Check

flowchart TD
    A([Phone opens PWA]) --> B[Summary Card\nN active · N warnings · daily cost]
    B --> C{Alerts present?}
    C -->|No| D[Scan agent list\nthumb-scroll, status dots]
    C -->|Yes| E[Alert banner at top\ntap to expand]
    E --> F[Alert Detail\nagent name, error, time, severity]
    F --> G{Action from phone?}
    G -->|Acknowledge| H[Mark acknowledged\nalert cleared]
    G -->|Terminate agent| I[Confirm dialog\nswipe-to-confirm]
    G -->|Escalate| J[Send Telegram message\nto self with deep link]
    I --> K[Agent terminated\nlist updates]
    H --> D
    D --> L{Need more detail?}
    L -->|Yes| M[Tap agent row\nmobile Session Inspector\nscrolling message list]
    L -->|No| N([Done - close PWA])
    M --> N

Flow E: Multi-Agent Orchestration

flowchart TD
    A([Open Pipelines Panel]) --> B[Pipeline Builder\ndrag/drop agent nodes]
    B --> C[Define stages\nsequential or parallel]
    C --> D[Set handoff conditions\noutput routing rules]
    D --> E[Name pipeline\nsave as template]
    E --> F[Trigger pipeline\nmanual or cron-linked]
    F --> G[Pipeline View\nall stages shown with live status]
    G --> H{Monitor stage progress}
    H -->|Stage running| I[Stage card: active\nlink to session inspector]
    H -->|Stage complete| J[Output preview\npassed to next stage]
    H -->|Stage failed| K[Failure card highlighted\nretry or skip options]
    J --> L{More stages?}
    L -->|Yes| H
    L -->|No| M[Pipeline complete\naggregate cost + output summary]
    K --> N{User decision}
    N -->|Retry| H
    N -->|Skip| L
    N -->|Abort pipeline| O[All stages terminated\nfailure recorded]
    M --> P[Review results\nexport or link to GitHub PR]

5. System Architecture (Stack-Agnostic)

5.1 Component Map

graph TB
    subgraph External["External Systems"]
        GW[OpenClaw Gateway\nWebSocket + REST API]
        CC[Claude Code\nLocal process / ACP]
        CD[Codex\nOpenAI API]
        GEM[Gemini CLI\nLocal process]
        GH[GitHub API]
        TG[Telegram Bot API]
        DS[Discord Bot API]
    end

    subgraph Core["Mission Control Core"]
        GA[Gateway Adapter\nWebSocket client + REST client\nreconnect, heartbeat, auth]
        EB[Event Bus\npub/sub, event normalization\nin-memory + persistent queue]
        AR[Agent Registry\nagent list, session state\nstatus cache, metadata]
        TQ[Task Queue\nwork items, pipelines\ncron schedule, retry logic]
        AL[Auth Layer\nidentity, sessions, MFA\nrole enforcement, tokens]
        NR[Notification Router\nalert rules engine\nseverity routing\nsnooze/ack state]
    end

    subgraph UI["UI Shell"]
        WEB[Web App\nSPA with SSR shell]
        MB[Mobile Bridge\nPWA + responsive layout\nTouch-optimized panels]
        WS2[WebSocket to clients\nreal-time push to browsers]
    end

    subgraph Storage["Storage"]
        DB[(Primary Database\nsessions, costs, cron, users)]
        CACHE[(Cache Layer\nactive session state\ncost aggregates)]
        LOGS[(Event Log\nappend-only event history)]
    end

    GW -->|WebSocket events| GA
    GW -->|REST responses| GA
    GA -->|normalized events| EB
    EB -->|session events| AR
    EB -->|task events| TQ
    EB -->|alert triggers| NR
    AR --> DB
    TQ --> DB
    AL --> DB
    AR --> CACHE
    EB --> LOGS

    NR -->|alerts| TG
    NR -->|alerts| DS
    GA -->|commands| GW

    CC -->|ACP protocol| GA
    CD -->|status + output| GA
    GEM -->|stdout capture| GA
    GH -->|PR/issue events| TQ

    WEB <-->|API + WebSocket| WS2
    MB <-->|API + WebSocket| WS2
    WS2 <-->|real-time events| EB
    AL --> WEB
    AL --> MB

5.2 Data Flow

Inbound (OpenClaw → system → user):

  1. OpenClaw gateway emits events over WebSocket: session.created, session.updated, message.sent, message.received, tool.called, tool.result, session.ended, session.error, cron.triggered, cron.completed, cron.failed, cost.updated.
  2. Gateway Adapter receives raw events, normalizes them into a canonical event schema (adds timestamps, deduplicates, handles reconnects transparently).
  3. Event Bus routes normalized events to subscribers: Agent Registry (updates status cache), Task Queue (updates task state), Notification Router (evaluates alert rules), and the WebSocket server (pushes to connected clients).
  4. Connected UI clients receive real-time updates. The web app re-renders affected panels. Mobile bridge delivers push notifications for critical events when the app is backgrounded.
  5. All events are appended to the Event Log for history queries. Cost events are aggregated into the Cache Layer for fast dashboard reads.

Outbound (user → system → OpenClaw):

  1. User action in UI (spawn agent, send message, terminate, trigger cron) hits the backend REST API.
  2. Auth Layer validates the request and enforces role permissions.
  3. Task Queue optionally logs the command as a task item (for pipeline tracking).
  4. Gateway Adapter issues the command to OpenClaw gateway via REST or WebSocket.
  5. The resulting gateway event flows back through the inbound path, closing the loop.

Coding Agent Integration (Claude Code / Codex / Gemini):

5.3 Integration Points

System Protocol Direction What we use it for
OpenClaw Gateway WebSocket (events) + REST (commands) Bidirectional Primary data source: all agent sessions, cron, costs, config
Claude Code ACP over WebSocket Bidirectional Spawn, monitor, and direct Claude Code sessions
Codex OpenAI Responses API Outbound command, inbound stream Spawn Codex tasks, receive streaming output
Gemini CLI Local subprocess (stdin/stdout) Bidirectional Spawn Gemini tasks, capture output via stdout reader
Telegram Bot API HTTPS REST Outbound Alert delivery, mobile quick-check notifications
Discord Bot API HTTPS REST + WebSocket Bidirectional Alert delivery, slash command reception from Discord
GitHub API HTTPS REST + Webhooks Bidirectional Issue/PR linking, CI status, webhook-triggered task creation
Tailscale API HTTPS REST (optional) Inbound Device presence, auto-detect when phone is on home network

6. Feature Specifications

F1: Live Agent Dashboard

What it does: Renders a real-time panel of all agent sessions — active, idle, and recently completed — with status indicators, model label, elapsed time, token count, and current cost.

Inputs: WebSocket event stream from Gateway Adapter. Polling fallback (REST GET /sessions) if WebSocket is unavailable.

Outputs: Auto-updating table/card grid. Each entry shows: session ID (truncated), agent name/persona, model, status (dot indicator: green/yellow/red/gray), message count, tokens in/out, cost USD, elapsed time, last activity timestamp. Clicking any row opens Session Inspector.

Edge cases: - Gateway WebSocket drops → show stale-data banner, attempt reconnect every 5s, fall back to polling. - >100 concurrent sessions → virtualized list rendering (only render visible rows). - Session in error state has no readable reason → show "Error (no detail)" and link to raw event log. - Sessions from multiple agents with the same name → disambiguate by session ID suffix.

Acceptance criteria: - Sessions appear within 2 seconds of gateway event. - Status updates propagate without full page refresh. - Dashboard is usable with 50+ sessions without scroll jank. - Stale-data state is clearly communicated (timestamp of last update visible). - All session fields are present and accurate when compared against gateway REST response.

F2: Session Inspector

What it does: Full drill-down view of a single agent session: complete message history, tool call/result pairs, token usage over time, and all metadata.

Inputs: Session ID (from dashboard row click or direct URL). REST GET /sessions/:id for initial load; WebSocket subscription for live updates if session is active.

Outputs: Scrollable message timeline (user/assistant/tool turn structure). Token counter per message. Tool call cards showing name, inputs, outputs. Cost timeline chart. Session metadata panel (model, persona, channel, start time, duration). For active sessions: live streaming of new messages appended in real-time.

Edge cases: - Session with 10,000+ messages → paginate (load last N, load-more up). Do not load full history on mount. - Tool call with very large output (file contents, long JSON) → collapsed by default, expandable. - Session errors mid-stream → show error message inline in timeline with red callout. - Concurrent viewer while session is active → WebSocket subscription shares the same event, no duplicate subscriptions.

Acceptance criteria: - Inspector opens within 1.5s for sessions with <500 messages. - Live messages appear within 500ms of gateway event. - Tool calls are visually distinct from chat messages. - Token count per message is displayed. - Inspector URL is deep-linkable (shareable).

F3: Agent Spawn

What it does: Modal dialog to launch a new agent session on the OpenClaw gateway with specified parameters.

Inputs: User selects model (dropdown), agent persona (dropdown of configured agents or free-text), initial prompt (textarea), target channel (optional), task link (optional kanban card or GitHub issue).

Outputs: POST to gateway /sessions endpoint. On success: session appears in Agent List, inspector opens automatically. On failure: error message with gateway error detail.

Edge cases: - Selected model not available (quota, deprecated) → pre-flight validation before submit; show model status from gateway. - Prompt is empty → require non-empty; warn if <10 characters. - Gateway unreachable at spawn time → queue spawn for retry with user notification. - Agent persona not configured → allow free-text but warn it won't use an existing SOUL/IDENTITY.

Acceptance criteria: - Session appears in dashboard within 3s of spawn. - All available models from gateway config populate the dropdown automatically. - Spawn failure shows actionable error message, not generic "something went wrong." - Spawned sessions are identifiable by their persona name in the list.

F4: Session Control

What it does: Allows sending messages to, or terminating, any active agent session from the dashboard.

Inputs: User types message in command input (within Session Inspector) and submits, or clicks Terminate button.

Outputs: Message → POST /sessions/:id/message, gateway delivers to agent, response streams back into Inspector. Terminate → POST /sessions/:id/terminate, session status changes to Terminated.

Edge cases: - Send message to completed/terminated session → disabled input with tooltip explanation. - Terminate session that is already completing (race condition) → idempotent; show "session ended" if it was already done. - Message rejected by gateway (e.g. session locked) → surface gateway error inline. - Long-running terminate (agent doesn't stop cleanly) → timeout after 30s, mark as force-terminated.

Acceptance criteria: - Message delivered to gateway within 1s of submit. - Terminate action requires confirmation dialog (no accidental kill). - Terminated sessions show clear visual distinction from completed sessions. - Command input is disabled/hidden for non-active sessions.

F5: Cron Job Viewer

What it does: Displays all scheduled cron jobs with their schedule, next run time, last run outcome, and run history.

Inputs: REST GET /cron from gateway. Refreshed on page load and on cron-related events from WebSocket.

Outputs: Table of jobs: name, expression (human-readable: "every 5 min"), next run (relative: "in 3m"), last run status (✅ / ❌), last run duration, last run cost. Clicking a job opens job detail with run history list and last output preview.

Edge cases: - Cron expression not parseable on frontend → display raw expression, skip human-readable translation. - Job that has never run → show "Never run" in last run column. - Job currently running → show in-progress indicator with elapsed time. - Gateway returns 0 cron jobs → show empty state with link to documentation.

Acceptance criteria: - All gateway-configured cron jobs appear with correct schedule. - Human-readable schedule translation is accurate for standard expressions. - Run history shows at minimum last 10 runs. - Currently-running jobs update in real-time without page refresh.

F6: Cost Dashboard

What it does: Aggregated view of token usage and dollar cost across all sessions, broken down by model, agent, and time period.

Inputs: Cost events from Event Bus; pre-aggregated totals from Cache Layer. Time range selector (today, 7 days, 30 days, custom).

Outputs: Summary cards: today's total, week total, month total, most expensive agent, most used model. Bar chart: daily cost by model. Table: top 10 most expensive sessions. Token usage breakdown: input vs output vs cache tokens.

Edge cases: - Cost data unavailable (gateway not reporting) → show estimated cost based on token count × known model pricing table. Label as "estimated." - Currency display → always USD, configurable decimal precision. - Zero-cost sessions (free-tier or local models) → show $0.00 explicitly, not blank.

Acceptance criteria: - Totals match gateway-reported cost data within 1% rounding. - Chart updates when time range changes without full page reload. - Cost per session is visible from the main agent list (no need to drill in).

F7: Real-time Event Stream

What it does: A live, scrolling feed of all gateway events — the equivalent of a structured tail -f for the entire agent infrastructure.

Inputs: All events from Event Bus, rendered in insertion order.

Outputs: Scrolling list of events with timestamp, event type (colored badge), agent name, and payload summary. Filterable by: agent, event type, severity. Pause/resume scroll. Copy event payload button.

Edge cases: - Very high event volume (multi-agent pipeline, hundreds/sec) → throttle rendering to 30fps; batch DOM updates; show "N events/sec" indicator. - Browser tab backgrounded → buffer events, drain on focus. - Event payload contains sensitive data (tokens, passwords) → redact known sensitive fields before display.

Acceptance criteria: - Events appear within 500ms of gateway emission. - Filter by event type works without page reload. - High-volume scenarios (>50 events/sec) do not freeze the browser tab.

F8: Alert System

What it does: Evaluates a configurable rule set against incoming events and delivers alerts via Telegram, Discord, and in-app notification.

Inputs: Event Bus events + configured alert rules. Alert rules: condition (event type, threshold, regex match), severity (info/warning/critical), delivery channel.

Outputs: In-app notification badge + alert panel. Telegram message to Sean's chat. Discord message to configured channel. Alert state: unacknowledged / acknowledged / snoozed.

Edge cases: - Alert delivery fails (Telegram rate limit, Discord outage) → retry 3×, fall back to in-app only, log delivery failure. - Alert storm (many events matching rule in short period) → deduplicate: max 1 alert per rule per 5 minutes. - Rule misconfiguration (regex error) → validate rule at save time; disable rule if it throws at eval time.

Acceptance criteria: - Critical alerts delivered to Telegram within 30s of triggering event. - In-app alerts visible without page reload. - Alert acknowledgment persists across sessions (stored in DB). - Alert history viewable for last 30 days.

F9: Auth + Access Control

What it does: Secures the dashboard behind authentication. Only authorized users can access any part of the system.

Inputs: Login form (username + password). Optional TOTP second factor. Session token for subsequent requests.

Outputs: Authenticated session cookie/JWT. Role assignment enforced on all API endpoints and UI routes. Unauthenticated requests redirect to login.

Edge cases: - Brute-force protection → rate limit login attempts (5 failures → 15-minute lockout). - Session expiry → configurable; default 24h; silent refresh if user is active. - Gateway token stored in backend only → never exposed to frontend. Frontend calls backend; backend calls gateway.

Acceptance criteria: - All API endpoints return 401 for unauthenticated requests. - TOTP setup and validation works (QR code + manual entry). - Gateway API token is never sent to or visible in the browser. - Role-based permission enforcement tested for Owner, Admin, and Viewer.

F10: Mobile-Responsive UI

What it does: Ensures all Tier 1 views are usable on a phone screen (350px+) with touch-friendly interaction targets.

Inputs: Responsive CSS layout; touch events.

Outputs: Collapsed navigation (hamburger or bottom tab bar on mobile). Card-based layouts replacing tables. Minimum 44px touch targets. Critical actions (terminate, spawn) require swipe-to-confirm on mobile to prevent accidental taps.

Edge cases: - Landscape phone orientation → layout adapts gracefully, no horizontal scroll. - Slow mobile connection → skeleton loading states for all panels; no blank screens. - PWA installation → manifest.json with correct icons; works offline for cached dashboard skeleton.

Acceptance criteria: - All Tier 1 screens pass basic Lighthouse mobile score (>70). - Session Inspector is scrollable and readable on a 375px-wide screen. - PWA installs on iOS Safari and Android Chrome without errors.

7. Screen Inventory

Dashboard Section

Screen Purpose Key Elements
Main Dashboard At-a-glance system health Agent status summary cards, cost today, active alerts banner, quick links to top agents, recent event preview
Agent List All sessions in one view Live-updating table/cards, status dots, model labels, cost column, sortable columns, search/filter bar
Session Inspector Deep dive into one session Message timeline, tool call cards, token counter, cost timeline chart, metadata sidebar, command input (if active)
Event Stream Live event firehose Scrolling event feed, event type filter, agent filter, pause/resume, payload viewer

Agents Section

Screen Purpose Key Elements
Spawn Agent Launch new session Modal: model selector, persona picker, prompt textarea, channel selector, task link, submit
Agent Config View/edit agent persona config Persona name, soul/identity display, channel assignments, model defaults, permissions. Read-only for non-Owner.

Tasks Section

Screen Purpose Key Elements
Task Kanban (Tier 2) Visual task pipeline Column board: Inbox / In Progress / Review / Done, drag-and-drop cards, session link per card, GitHub issue link
Pipeline Builder (Tier 2) Multi-agent pipeline config Node-based editor, agent assignment per stage, sequential/parallel toggle, handoff condition editor
Pipeline Monitor (Tier 2) Live pipeline execution view Stage cards with real-time status, aggregate cost, error callout, retry/skip buttons

Cron Section

Screen Purpose Key Elements
Cron Job List All scheduled jobs Schedule, next run countdown, last run status, cost, run toggle, manual trigger button
Cron Job Detail Single job history + config Run history table, last output preview, error log, edit button (Tier 2), manual trigger
Cron Editor (Tier 2) Create/edit cron job Expression input with preview, target agent, prompt template, timezone, save/cancel

Cost Section

Screen Purpose Key Elements
Cost Dashboard Spend overview Summary cards (today/week/month), bar chart by day/model, top sessions table, token breakdown
Cost Detail Per-session cost drill-down Token timeline, model × tokens table, session context link
Budget Config (Tier 2) Spending limits Daily/monthly budget input per agent or global, alert threshold %, enable/disable

Alerts Section

Screen Purpose Key Elements
Alert Center All current and historical alerts Unacknowledged list (badged count), acknowledged history, severity filter, acknowledge/snooze actions
Alert Rules (Tier 2) Configure alert conditions Rule list, add/edit rule modal: trigger type, condition, threshold, channel, severity

Settings Section

Screen Purpose Key Elements
Gateway Config OpenClaw gateway connection Gateway URL, WebSocket URL, connection status, token (masked), test connection button
User Management Manage access User list, roles, invite user, revoke access, TOTP management
Notification Channels Configure delivery endpoints Telegram bot token + chat ID, Discord webhook URL, email (Tier 2), test button per channel
Profile / Auth Current user settings Change password, TOTP setup, active sessions, theme toggle
System Health Mission control self-monitoring Uptime, DB size, event queue depth, WebSocket connection status, last heartbeat time

8. Notification & Alerting Design

Alert Taxonomy

Severity Color Sound Delivery
Info Blue None In-app only
Warning Yellow Soft chime In-app + optional Telegram
Critical Red Urgent tone In-app + Telegram + Discord

Trigger Catalog

Trigger Default Severity Condition
Agent session error Warning session.error event received
Agent session crash / unrecoverable Critical session.error + no recovery in 60s
Agent unexpectedly terminated Warning session.ended with abnormal exit code
Gateway connection lost Critical WebSocket disconnected + reconnect failed 3×
Cron job failed Warning cron.failed event
Cron job missed schedule Warning Expected run time passed by >2× interval with no trigger
Daily cost threshold reached Warning Configurable %, default 80% of daily budget
Daily cost limit exceeded Critical 100% of daily budget
Session cost spike Warning Single session exceeds configurable threshold (default $1.00)
Gateway auth failure Critical 401/403 from gateway API
No events in N minutes Warning Event stream silent for >10 minutes during business hours
New agent spawned Info session.created (optional, disabled by default)
Pipeline stage failure Warning Pipeline stage returns error state
Pipeline total failure Critical All retry attempts exhausted for a pipeline stage

Delivery Routing Logic

if severity == Critical:
  → always: in-app alert badge + alert panel entry
  → always: Telegram (Sean's personal chat)
  → if Discord configured: Discord #alerts channel
  → if previous identical alert was sent < 5 min ago: suppress duplicate, increment count

if severity == Warning:
  → always: in-app alert badge
  → if user has enabled Telegram for warnings: Telegram
  → Discord: only if explicitly configured per rule

if severity == Info:
  → in-app event feed only (not the alert badge)
  → never Telegram/Discord by default

Snooze / Acknowledge / Escalate

9. Tech Stack Recommendation

Frontend: Next.js (React)

Backend/API: Node.js with Hono (or Fastify)

Realtime: WebSocket (native) via the backend API server

Database: SQLite (via Turso or local file)

Auth: Better Auth (or next-auth v5 / Auth.js)

Mobile: Progressive Web App (PWA)

Deployment: Docker Compose on Proxmox LXC behind Traefik

Cross-Cutting Concerns

Testing Strategy

CI/CD Approach

Security Considerations

Observability (monitoring the monitor)

10. Implementation Phases

Phase 0: Foundation (Week 1–2)

Everything that must be true before feature work begins. Nothing in Phase 1 should block on setup.

Deliverables: - [ ] Repository created, monorepo structure defined (/app, /packages/types, /packages/gateway-client) - [ ] Docker Compose configuration: app service + named volume for SQLite - [ ] Traefik labels configured; app accessible at mission-control.yourdomain.com via Tailscale - [ ] CI/CD pipeline: lint + type-check passes on empty repo - [ ] Database schema defined and migrated: sessions, events, cron_runs, alerts, users, alert_rules - [ ] Gateway Adapter package: connects to OpenClaw WebSocket, parses all known event types into canonical schema, handles reconnect - [ ] Auth system bootstrapped: login page, session tokens, Owner user created - [ ] Basic Next.js app shell: authenticated layout, navigation skeleton, dark mode default - [ ] Vitest + Playwright configured; one smoke test passing in CI - [ ] Storybook configured with one Button component

Definition of done: A developer can log in, see the empty dashboard shell, and confirm the gateway adapter is receiving events from OpenClaw.

Phase 1: MVP (Week 3–6)

All Tier 1 features shipped. The system is usable as a real operations tool.

Week 3: F1 (Agent List) + F7 (Event Stream) + F9 (Auth refinement) - Live agent list rendering gateway sessions - Real-time event stream panel - Auth roles: Owner + Viewer working

Week 4: F2 (Session Inspector) + F3 (Spawn Agent) + F4 (Session Control) - Full session drill-down view - Spawn dialog and terminate/message controls - Deep-linkable session URLs

Week 5: F5 (Cron Viewer) + F6 (Cost Dashboard) - Cron list with run history - Cost aggregation and charts

Week 6: F8 (Alerts) + F10 (Mobile) + integration testing - Alert rules engine + Telegram delivery - Full mobile responsive pass on all screens - E2E tests for all core flows - Performance testing with 50+ simulated sessions

Definition of done (Phase 1): - All 10 Tier 1 features pass acceptance criteria - E2E tests passing for Flows A–D - System running on Sean's Proxmox LXC behind Traefik - Sean uses it as his primary agent monitoring tool for one full week before Phase 2 begins - No P0 bugs open

Phase 2: Enhanced (Week 7–12)

Tier 2 features. Each is a milestone; ship in priority order.

Milestone 2.1 (Week 7–8): Operational Power - F11: Cron Job Editor (UI-based cron creation/edit) - F15: Model Config Panel - F17: Notification Routing Config UI (manage alert rules from the dashboard) - F19: Cost Budgets & Thresholds

Milestone 2.2 (Week 9–10): Collaboration & Tracking - F12: Agent Task Kanban - F14: GitHub Integration (issue/PR linking, CI status) - F18: Session Search & Full-Text History

Milestone 2.3 (Week 11–12): Multi-Agent & Polish - F13: Multi-Agent Pipeline Builder + Monitor (Flow E) - F16: Skills & Plugins Viewer - F20: Dark/Light theme system + visual polish pass - Security audit: penetration test auth layer, review CSP, verify no token leakage

Phase 3: Polish & Scale (Week 13+)

Tier 3 features, performance hardening, and long-term maintainability.

Performance: - Virtualized lists for session tables (>500 sessions) - Event log archival (move events >90 days to cold storage) - Connection pooling / WAL mode optimization for SQLite under concurrent load - Lighthouse audit: target >85 mobile score

Tier 3 Features (priority order): 1. F26: Exported Reports (PDF/CSV) — highest ROI, simple to implement 2. F24: Agent Replay — high value for debugging 3. F22: 3D Agent Graph — visually impressive, lower operational value 4. F21: Voice Command Input — nice to have, complex to do well 5. F23: Predictive Cost Modeling — requires sufficient historical data (30+ days of usage) 6. F28: Multiplayer Collaboration — low priority for single-owner setup 7. F27: Plugin Marketplace — complex, dependency on ClawHub API stability 8. F25: Wake-Word Activation — mobile hardware dependency, complex

Hardening: - Database backup automation (daily SQLite dump to Proxmox backup storage) - Self-monitoring: dashboard health endpoint checked by OpenClaw cron + Telegram alert - Alert storm testing: verify deduplication logic under load - Documentation: API reference, deployment guide, configuration reference

11. Open Questions & Decisions Required

12. Success Metrics

Phase 0 Success (Week 2)

Phase 1 Success (Week 6)

Phase 2 Success (Week 12)

Phase 3 Success (Week 13+)

End of OpenClaw Mission Control Implementation Plan v1.0 Ready for Claude Code implementation handoff.